home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Pascal Super Library
/
Pascal Super Library (CW International)(1997).bin
/
BBS_UTL
/
BOI200P
/
BOI200.DOC
< prev
next >
Wrap
Text File
|
1992-12-13
|
28KB
|
610 lines
BOI Developer Reference Manual 2.00 12/15/92
BBS Onliner Interface 2.00 (Pascal)
(C) 1992 Andrew J. Mead
All Rights Reserved.
Contact:
POB 1155
Chapel Hill, NC 27514-1155
or
1:3641/417 FidoNet 75:7919/417 DoorNet
#1@9952 WWIVnet #1@9395 VirtualNet
Turbo Pascal and TP are registered trademarks of Borland International.
Borland Pascal and BP are registered trademarks of Borland International.
Sections in order of Appearance
1 Initial Statement
2 ShareWare Liscense Agreement
3 Registration Cost
4 Technical Support
5 Style Conventions
6 How to write an Onliner (overview)
7 Substitutions
8 Global Constants
9 Global Types
10 Global Static Variables (Typed Constants)
11 Global Variables
12 Unit Explanations
13 Features
14 Future Enhancements
15 Message Bases
1) Initial Statement.
Thanks to Kent Ogle, John Reid, Mike Robinson, Joe Dabrowski, and
Jochen Ott. The BOI 2.00 is the result of 8 months of intense
programming effort. I release the BOI 1.20 to the public two
years ago fully intending to continue developement. Two factors
conspired against me. The first was my getting a 40-50 hour/week
programming job. The second was lack of registrations and support
from the general public. I tend to blame the second on myself. I
was new to Shareware, and I misunderstood the market. I was
arguably the worst technical writer ever to hit the streets. I
still look back on the BOI 1.20 very proudly. I consider it a
fine piece of work. It took me only three months to write the
entire thing. I had owned a modem less than a year at that point.
Times have changed, and I've learned how to write documentation.
Earlier this year (1992), I finally was able to free up enough
time to look back on the BOI. For my own releases, I was up to
BOI 1.23 which only contained a couple minor changes from the BOI
1.20. For those of you familiar with the BOI 1.20, this release
may come as a complete surprise. There are nearly 1000 more lines
of source code, and the code that remains has been greatly
rewritten. I've also renamed all of the standard variables.
Thanks for taking the time to look at my product. I hope you like
it. I can be reached at the addresses found throughout the
documentation. Don't hesitate to contact me.
2) Shareware License Agreement
This package is ShareWare. If you use this package, you are
required to register it. If you merely use this package as a
learning tool, and you do not use any portions of it in your own
programming, you are not obligated to register.
If you write any software that uses the BBS Onliner Interface,
your opening copyright screen must include this after your own
copyright messages.
BBS Onliner Interface version 2.00
(C) 1992 Andrew J. Mead
All Rights Reserved.
Contact: POB 1155 Chapel Hill, NC 27514-1155
If you only use parts of the BOI, you can use this instead.
portions (C) 1992 Andrew J. Mead (BOI 2.00)
All Rights Reserved.
Contact: POB 1155 Chapel Hill, NC 27514-1155
If you alter the code, put your revision number AFTER the '2.00'
ie (version 2.00 rev 1a). I will maintain, and steadily
update the interface. If you have any ideas, suggestions, or
improvements, please send them to me. There is plenty of room for
enhancement, addition, and improvement in the interface.
3) Registration Costs
Here is a basic chart of costs ($US):
Standard Professional Standard+Pro Upgrade
North Carolina - $31.80 $53.00 $63.60
USA & Canada - $30.00 $50.00 $60.00
Other Countries - $33.00 $53.00 $66.00
This chart reflects registration fees, processing costs, and
taxes. It does not include your postage to me, or any of your
currency conversion costs.
Registration Options:
Standard Registration ($US25+fees)
Standard Registration gives you license to use the BOI or
portions thereof in any Shareware or Freeware software that you
may write. Registration will not expire, and you are entitled
to use any future public (non-beta) MS-DOS releases as well.
Professional Registration ($45US+fees)
Professional Upgrade from Standard Registration ($25US+fees)
Professional Registration gives you all the rights of the
Standard Registration. I also will make available to you (via
download from my BBS, or via Fido FREQ) current BOI betas. I
will also send you the current source code (you must sign the
non-disclosure agreement contained in the registration form) to
my online game Madness. You will also will have the option of
carrying the Fido Technology message area BOI-BETA.
Commercial Registration and License
If you intend to write commercial software with the BBS Onliner
Interface, or portions thereof, you will need to contact me
personally to negotiate an appropriate license agreement.
Note: All new registrations of the BOI 1.20 ($35US) received after
December 15th, 1992 will be treated as Standard Registrations.
Those received before June 30th, 1993 will be offered a $10US
credit towards upgrading to the Professional Registration that
is good until December 15, 1993.
Processing Fees
Canada and United States : $5.00
Others : $8.00
The processing fee is used to cover my diskette, postage, and
phone costs associated with staying in contact with registered
users.
4) Technical Support
I am always willing to offer support. I can be reached on my BBS.
Infinite Improbability BBS - Private Idaho BBS - The Old Same Place
+919-489-9446 (v32b)
1:3641/417 FidoNet @9395 VirtualNet
@9952 WWIVnet 75:7919/417 DoorNet
Programming support can also be found in the message area BOI-PROG
BOI-PROG is currently in private distribution among FidoNet
systems. If enough interest warrants, I will attempt to backbone
this echo. I can also be reached via postal mail, be sure to
include a self addressed stamped envelope to guarantee reply.
I am always looking for people to help with technical support.
5) Style Conventions.
This document, and my other documentation files, are 72 characters
wide. The document can be shifted to the right when printing to
allow for ring binder holes to be punched without text wrapping
around. There are no imbeded form feeds.
My programming style is:
- Capitalize procedure and function calls [WriteLn('sample')]
- Fully capitalize procedural declarations [Procedure DOTHIS;]
- Four space basic indentation scheme with matching begin..end
pairs offset two spaces.
- Nested procedures indented two spaces
- repeat..until code blocks include begin..end pair
- Const, Type, and Var are only capitalized for global blocks
- Blank statements supressed (remove unnecessary semi-colons)
- Procedural blocks are commented with all nested calls.
Functions are preceded with "f"
Interrupts are preceded with "i"
Objects are preceded with "o"
Program blocks are preceded with "p"
Unit blocks are preceded with "u"
Function TESTVAL : word;
Procedure INCCOUNTERS(cnta, cntb : longint);
begin {* fTestVal,IncCounters *}
end; {* fTestVal,IncCounters *}
6) How To Write an Onliner
The BBS Onliner Interface comes with a working online game (HiLo)
that you can compile and run! HiLo follows the same structure,
and uses much of the same code as most of my online games. By
examining HiLo, or modifying it into another game, you can see
how simple programming with the BOI can be. By using the BOI,
you, the programmer, need not be concerned with anything other
than writing the game or utility. The BOI handles communications,
the interface to the BBS, and video output.
To write an onliner, you'll need to include several units into
your Unit clause, put the proper values in DOORLIB.DAT, and
substitute certain BOI procedures, functions, and variables for
the ones you are currently using (see next section.)
The following is a working shell of an online game.
Program Onliner;
Uses
DOS,
CRT,
KEY,
BOIDECL,
DOORLIB,
GETCMBBS,
IOLIB,
SUPPORT;
Procedure PLAYGAME;
begin {* PlayGame *}
{ This is the main program block for your game }
end; {* PlayGame *}
begin {* pOnliner *}
if boi_allowavt then QueryUser(['Q','1'..'4')
else QueryUser(['Q','1','2']);
WriteCopy(false);
repeat
begin
PlayGame
EndGame('Players',playerpoints > 0,bois_points,
bois_highscore)
end
until not boi_replay
end. {* pOnliner *}
DOORLIB.DAT
You will need to create a copy of this include file for each of
the doors you write. This is the information that needs to be
supplied: (Sample data from HiLo's DOORLIB.DAT)
'HILOINFO.DOC', (* HiLo documentation filename *)
This is show to the user when GetCmBBS.GetCommand
encounters a fatal initialization condition.
'HILOHOF.TXT', (* HiLo text Hall of Fame filename *)
This is used by Support.EndGame.
'HILOHOF.DAT', (* HiLo data Hall of Fame filename *)
This is used by Support.EndGame.
'BOI.LOG', (* activity / error log filename *)
This can be overridden by use of environment variables.
'HiLo', (* game name *)
'2.00'); (* game version number *)
dl_progset : set of char = [#00];
(* valid additional command line switches *)
7) Substitutions
This is a quick list of Turbo Pascal Procedures, Functions, and
variables that should not be used in your online door. Where
applicable, the equivalent BOI procedure or variable is given.
Remember, this is only a guide. Most of these procedures are
to be avoided because they don't affect the remote screen, and
they don't update certain BOI variables (i.e. boi_l_textattr).
--Sample
TurboFunction BOIFunction necessity
Additional notes on what is going here
--Procedures and Functions
System.Append IOLib.OpenText recommended
Crt.AssignCrt -none-
This procedure should not be called
Crt.ClrEOL IOLib.ClrPortEOL required
Crt.ClrScr IOLib.ClrPortScr required
Crt.DelLine -none-
This procedure should not be called
Crt.GotoXY IOLib.GotoPortXY required
Crt.HighVideo -none-
Crt.InsLine -none-
This procedure should not be called
Crt.KeyPressed IOLib.PortKeyPressed required
Crt.LowVideo -none-
Crt.NormVideo -none-
Crt.NoSound -none-
System.Read (file) System.BlockRead recommended
Crt.ReadKey IOLib.ReadPortKey required
System.ReadLn IOLib.GetString required
System.Reset (file) IOLib.OpenFile recommended
System.Reset (text) IOLib.OpenText recommended
System.Rewrite (file) IOLib.OpenFile recommended
System.Rewrite (text) IOLib.OpenText recommended
Crt.Sound -none-
Crt.TextBackground IOLib.PortBackground required
Crt.TextColor IOLib.PortColor required
Crt.TextColor IOLib.TextPortColor required
Crt.TextMode -none-
This procedure should not be called
Crt.WhereX -none-
Crt.WhereY -none-
Extreme caution should be used with these two functions.
You should consider IOLib.SetPortXY and IOLib.ResetPortXY.
Crt.Window IOLib.PortWindow required
System.Write (video) IOLib.SendString(,false) required
System.WriteLn (video) IOLib.SendString(,true) required
For formatting output, you should use IOLib.IntStr,
IOLib.RealStr, and IOLib.PadStr.
System.Write (file) System.BlockWrite recommended
--System variables
crt.directvideo IOLib.SetLocalGraphMode
This variable should be left alone
crt.textattr boi_l_textattr required
Do not manually change boi_l_textattr. The procedure
IOLib.ChangeColor should be used instead. The variable
boi_r_textattr tracks the remote text attribute.
crt.windmin -none-
crt.windmax -none-
These variables should not be used
8) Global Constants
BOIDECL
boi_version = '2.00'
Current BBS Onliner Interface version number. This should
only be changed with permission.
read_only = $00 (open file for reading)
writeonly = $01 (open file for writing)
readwrite = $02 (open file for reading and/or writing)
File access modes.
denyall = $10 (deny all file access to others)
denywrite = $20 (deny write to file access to others)
denyread = $30 (deny read from file access to others)
denynone = $40 (allow others to read and/or write to file)
File sharing (DOS Share) modes. These are used by OpenFile
and OpenText. When calling either of those procedures you
should add one access mode to one sharing mode:
OpenFile(...,read_only + denynone,...);
SUPPORT
bois_highscore = true
bois_lowscore = false
bois_cash = true
bois_points = false
These are declared only to help increase the readability of
calling Procedure Support.EndGame.
9) Global Types
BOIDECL
ptrmask
This is used to allow easy access to a pointer's segment and
offset. This is used for absolute casting:
var
tempptr : pointer;
tempmsk : ptrmask absolute tempptr;
facctype (file access modes)
tasktype (Operating Systems/Environments)
boi_grmode (video character graphics modes)
boi_commode (remote communications modes)
boi_statmodes (remote user status line modes)
boi_dropmode (BBS drop file modes)
These simple enumerated types are used by the BOI to keep
track of its enviroment.
stdproc
This is declared for basic procedural variables.
10) Global Static Variables (Typed Constants)
BOIDECL
-setup
boi_local = true (local mode (no remote))
boi_echo = false (echo remote play on local console)
boi_quiet = false (supress output of bell (^G) to local
console)
boi_replay = false (allow user to play multiple games)
boi_statmode = sm_time (what to display on user status line)
dos_share = true (DOS Share is loaded)
boi_hoflim = 20 (how many scores in HOF user can have)
-time
boi_timeover = false (time has expired)
boi_againtime = 10 (mins) (minimum time for boi_replay checking)
boi_warntime = 5 (mins) (warn user about time remaining limit)
the following are updated 18.2 times per second by the BOI's
timer interrupt.
boi_ticks = $17fe80 (this initial value (24 hrs) is
re-initialized by GetCmBBS. When it
reaches zero (0), time has expired)
boi_stall = 0 (this counter increments. It is used
by ReadPortKey to detect user
inactivity)
boi_timer = 0 (this counter increments. It is the
opposite of boi_ticks. It shows
just how long the game has been
active. This should be used instead
of any calls to MemL[$40:$0C])
boi_stime = 0 (this variable holds the last timer
tick at which IOLib.UpdateStatLine
was called)
-communications
boi_checkcd = true (carrier drop can be detected)
boi_cdlost = false (carrier has been lost during play)
boi_portnum = 0 (0==COM1, 1==COM2, etc...)
boi_cmode = com_none (internal BOI flag)
boi_str = ' No Comm' (displayed on User Status Line)
foss_init = $00 (bit flags detailing if and how
FOSSIL can be used. See source
code (GetCmBBS) for details)
The following are used by the BOI's internal comm routines.
If local play or FOSSIL routines are used, these are ignored.
boi_ctsrts = false (CTS/RTS handshaking is being used by
internal comm routines)
boi_portadd = $03F8 (base port address for communications)
boi_portint = $0C (Interrupt used by IRQ)
boi_picmask = $EF (enabling mask for Programmable
Interrupt Controller (IRQ0..IRQ7))
boi_pic2msk = $00 (enabling mask for second or cascade
PIC (IRQ8..IRQ15))
boi_cascade = false (IRQ in use is on cascade PIC)
boi_portstatus = false (internal Async routines active)
-video
boi_r_color = false (remote wants color/monochrome)
boi_l_color = false (local wants color/monochrome)
boi_allowavt = false (AVATAR/1 graphics are allowed)
boi_ansiarr (ANSI codes mapped over color values)
boi_r_grmode = gr_ansi (remote graphics mode)
boi_l_grmode = gr_tpcrt (local graphics mode)
-miscellaneous
boi_plusidx = 0 (These variables are used by GetCmBBS
boi_minusidx = 0 to let the program know that it needs
boi_equalidx = 0 to perform additional command line
boi_closeidx = 0 processing for door specific command
boi_openidx = 0 line arguments. Pass the value to
boi_dotidx = 0 ParamStr())
boi_dmode = dfnone (drop file that was processed)
boi_nextchar = #$00 (used to feed a character to GetString
KEY
key_regnum = 'N/A' (Registration number)
key_regstr = 'Unregistered Version'
(name of BBS that has registered)
key_registered = false (game has been registered)
key_regname = 'Your SysOp'
(name of registrant)
11) Global Variables
BOIDECL
-setup
boi_gamepath (path/filespec to current executable
"C:\BBS\GAME\HILO.EXE")
boi_gamedir (path to current excecutable "C:\BBS\GAME\")
boi_gamename (current game file "HILO")
boi_gameext (current executable extension ".EXE"
boi_tasker (current operating system/environment)
boi_tvers (operating system version number)
boi_tstr (string description of current operating system)
boi_tintr (basic interrupt to operating systems functions)
in_dos (in_dos flag pointer)
BOI_Wait (procedure to be called when giving up timeslice)
BOI_Crit (procedure to call when beginning critical task)
BOI_Safe (procedure to call when ending critical task)
-time
boi_starttime (starting time (hr,min,sec) of game)
boi_startdate (starting date (yr,month,day) of game)
boi_usetime (game is a timed game)
boi_gametime (old variable indicating time in minutes, unused)
boi_ticksleft (timer ticks left to play (1092 per minute))
boi_timexp (time has expired indicator)
-video
boi_pagelength (size of remote player's screen in lines)
-player
boi_username (player's alias/real name)
boi_usename (boi_username is valid)
boi_realname (player's real name if boi_username is alias)
boi_usereal (boi_realname is valid)
-miscellaneous
boi_texthof (pathfilespec for text Hall of Fame)
SUPPORT
playerpoints (playerscore variable)
12) Unit Explanations
BOIDECL
This unit is the basic foundation upon which the other units are
built. This is where the vast majority of global variables and
values are defined and initialized. The initialization code for
this unit installs the BOI's timer interrupt and checks to see
if the door is running under a multitasker.
KEY
This is just a shell. You'll have to write your own routines
for this one.
DOORLIB
This unit provides basic information to the BOI about your door.
You need to maintain a seperate DOORLIB.DAT file for each of
your doors, and make sure that this unit is rebuilt upon
compilation.
GETCMBBS
This self-initializing unit processes the command line, and
then initializes most of the system variables and calls the
routines to start remote communications.
This unit is the most replaceable. If you wish to write BBS
specific doors, you merely need to insert your own command line
processing routines. With your own routines, you can get any
additional dropfile information your door may require.
ASYNC
This unit contains the BOI's internal Async routines and its
FOSSIL routines. I recommend that you do NOT include this unit
in your program's Uses clause. It functions best when left
undisturbed. If you must access it, you should use the various
hooks available through the unit Support.
This unit does not initialize itself (GetCmBBS gets the ball
rolling with a call to IOLib.SetPort). It does, however, clean
up after itself. The BOI is very fault tolerant.
IOLIB
This is where it's at. This unit contains all of the video,
input, output, and file routines.
IOSUPP
This unit merely exists as a hook off of IOLib.ReadPortKey. It
is used to decipher function key presses on the local keyboard.
SUPPORT
This is a collection of additional routines that you may or may
not wish to use. It contains a Copyright screen, Hall of Fame
routines, and a text file displayer.
13) Features
o Distributed as Source Code
o FOSSIL driver support
o Internal Asynchronious routines
o non-standard IRQ/port address communications supported
o IRQs on second PIC supported (IRQ8..IRQ15)
o ANSI graphics support
o AVATAR/1 graphics support
o highly optimized video routines - redundant calls stripped
o local BIOS video and direct video modes
o local/remote video modes are seperately configureable
o multiple user status line display options
o file sharing/locking supported
o DESQview aware
o Windows aware
o OS/2 DOSbox aware
o gives up time to multi-taskers
o reads 18 different drop file formats
o runs directly under virtually all MS-DOS BBS software
o will compile as-is under TP5, TP55, TP60, and TP7
14) Future Enhancements
Coming Soon: (on the drawing board, code fragments exists)
o GT Power support (ran out of time to include in this release)
o activity logging
o enhanced error trapping and logging
o natural language file support
o config file script language
o record locking/sharing
o additional graphics modes (YALEbbs, etc...)
o switch to Turbo Pascal 7.0 baseline
Longer Range: (just some things I'm considering)
o object orientation
o comm routines for multiport boards (APIs needed)
o write language file compiler/decompiler
o ANSI sound or similiar
o use BP7 .DLLs for multinode engine
o take advantage of other new TP7 and BP7 features
o add transfer protocol engine (Xmodem, Zmodem)
o OS/2 version (compiler availability, additional registration)
o WinNT version (compiler availability, additional registration)
15) Message Bases
If interest warrants, I am willing to contribute to support echos
in any of the more common hobby networks. I am personally in
FidoNet, WWIVnet, DoorNet, and VirtualNet. I have access to
RIME and GT PowerNet. I can get access to USEnet and Internet.
I have the following areas available from my BBS. These are Fido
Technology Network (FTN) compatible message areas. If interest
warrants, I will attempt to get the first two areas backboned in
Zone 1 (North America).
BOI-GAMES
This is for discussion of any doors written with the BBS Onliner
Interface. This is intended for users and SysOps to communicate
with eachother and door authors.
BOI-PROG
This is for discussion of the latest public release version of
the BBS Onliner Interface. Code fragments, ideas, and
suggestions are welcome. I am willing to answer questions, but
I will not comment on any beta features.
BOI-BETA
This echo is restricted. It is only available to those who have
paid for a Professional Registration. This echo will be a
clearing house for ideas and discussion of beta versions of the
BBS Onliner Interface.
END BOI Developer Reference Manual